<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>2.&nbsp;Using XMLUnit</title><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"><link rel="start" href="index.html" title="XMLUnit Java User's Guide
    
  "><link rel="up" href="index.html" title="XMLUnit Java User's Guide
    
  "><link rel="prev" href="index.html" title="XMLUnit Java User's Guide
    
  "><link rel="next" href="ar01s03.html" title="3.&nbsp;Comparing Pieces of XML"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">2.&nbsp;Using XMLUnit</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="index.html">Prev</a>&nbsp;</td><th align="center" width="60%">&nbsp;</th><td align="right" width="20%">&nbsp;<a accesskey="n" href="ar01s03.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="Using XMLUnit"></a>2.&nbsp;Using XMLUnit</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Requirements"></a>2.1.&nbsp;Requirements</h3></div></div><div></div></div><p>XMLUnit requires a JAXP compliant XML parser virtually
      everywhere.  Several features of XMLUnit also require a JAXP
      compliant XSLT transformer.  If it is available, a JAXP
      compliant XPath engine will be used for XPath tests.</p><p>To build XMLUnit at least JAXP 1.2 is required, this is
      the version provided by the Java class library in JDK 1.4.  The
      JAXP 1.3 (i.e. Java5 and above) XPath engine can only be built
      when JAXP 1.3 is available.</p><p>As long as you don't require support for XML Namespaces or
      XML Schema, any JAXP 1.1 compliant implementations should work
      at runtime.  For namespace and schema support you will need a
      parser that complies to JAXP 1.2 and supports the required
      feature.  The XML parser shipping with JDK 1.4 (a version of
      Apache Crimson) for example is compliant to JAXP 1.2 but doesn't
      support Schema validation.</p><p>XMLUnit is supposed to build and run on any Java version
      after 1.3 (at least no new hard JDK 1.4 dependencies have been
      added in XMLUnit 1.1), but it has only been tested on JDK 1.4.2
      and above.</p><p>To build XMLUnit JUnit 3.x (only tested with JUnit 3.8.x)
      is required.  It is not required at runtime unless you intend to
      use the <code class="literal">XMLTestCase</code> or
      <code class="literal">XMLAssert</code> classes.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Basic Usage"></a>2.2.&nbsp;Basic Usage</h3></div></div><div></div></div><p>XMLUnit consists of a few classes all living in the
      <code class="literal">org.custommonkey.xmlunit</code> package.  You can
      use these classes directly from your code, no matter whether you
      are writing a unit test or want to use XMLUnit's features for
      any other purpose.</p><p>This section provides a few hints of where to start if you
      want to use a certain feature of XMLUnit, more details can be
      found in the more specific sections later in this
      document.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Basic: Comparing Pieces of XML"></a>2.2.1.&nbsp;Comparing Pieces of XML</h4></div></div><div></div></div><p>Heart and soul of XMLUnit's comparison engine is
        <code class="literal">DifferenceEngine</code> but most of the time you
        will use it indirectly via the <code class="literal">Diff</code>
        class.</p><p>You can influence the engine by providing (custom)
        implementations for various interfaces and by setting a couple
        of options on the <code class="literal">XMLUnit</code> class.</p><p>More information is available in <a href="ar01s03.html" title="3.&nbsp;Comparing Pieces of XML">Section&nbsp;3, &ldquo;Comparing Pieces of XML&rdquo;</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Basic: Validating"></a>2.2.2.&nbsp;Validating</h4></div></div><div></div></div><p>All validation happens in the
        <code class="literal">Validator</code> class.  The default is to
        validate against a DTD, but XML Schema validation can be
        enabled by an option (see
        <code class="literal">Validator.useXMLSchema</code>).</p><p>Several options of the <code class="literal">XMLUnit</code> class
        affect validation.</p><p>More information is available in <a href="ar01s04.html" title="4.&nbsp;Validating XML Documents">Section&nbsp;4, &ldquo;Validating XML Documents&rdquo;</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="XSLT Transformations"></a>2.2.3.&nbsp;XSLT Transformations</h4></div></div><div></div></div><p>The <code class="literal">Transform</code> class provides an easy
        to use layer on top of JAXP's transformations.  An instance of
        this class is initialized with the source document and a
        stylesheet and the result of the transformation can be
        retrieved as a <code class="literal">String</code> or DOM
        <code class="literal">Document</code>.</p><p>The output of <code class="literal">Transform</code> can be used
        as input to comparisons, validations, XPath tests and so on.
        There is no detailed sections on transformations since they
        are really only a different way to create input for the rest
        of XMLUnit's machinery.  Examples can be found in <a href="index.html#Comparing XML Transformations" title="1.6.&nbsp;Comparing XML Transformations">Section&nbsp;1.6, &ldquo;Comparing XML Transformations&rdquo;</a>.</p><p>It is possible to provide a custom
        <code class="literal">javax.xml.transform.URIResolver</code> via the
        <code class="literal">XMLUnit.setURIResolver</code> method.</p><p>You can access the underlying XSLT transformer via
        <code class="literal">XMLUnit.getTransformerFactory</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="XPath Engine"></a>2.2.4.&nbsp;XPath Engine</h4></div></div><div></div></div><p>The central piece of XMLUnit's XPath support is the
        <code class="literal">XpathEngine</code> interface.  Currently two
        implementations of the interface exist,
        <code class="literal">SimpleXpathEngine</code> and
        <code class="literal">org.custommonkey.xmlunit.jaxp13.Jaxp13XpathEngine</code>.</p><p><code class="literal">SimpleXpathEngine</code> is a very basic
        implementation that uses your XSLT transformer under the
        covers.  This also means it will expose you to the bugs found
        in your transformer like the transformer claiming a stylesheet
        couldn't be compiled for very basic XPath expressions.  This
        has been reported to be the case for JDK 1.5.</p><p><code class="literal">org.custommonkey.xmlunit.jaxp13.Jaxp13XpathEngine</code>
        uses JAXP 1.3's <code class="literal">javax.xml.xpath</code> package and
        seems to work more reliable, stable and performant than
        <code class="literal">SimpleXpathEngine</code>.</p><p>You use the <code class="literal">XMLUnit.newXpathEngine</code>
        method to obtain an instance of the
        <code class="literal">XpathEngine</code>.  As of XMLUnit 1.1 this will
        try to use JAXP 1.3 if it is available and fall back to
        <code class="literal">SimpleXpathEngine</code>.</p><p>Instances of <code class="literal">XpathEngine</code> can return
        the results of XPath queries either as DOM
        <code class="literal">NodeList</code> or plain
        <code class="literal">String</code>s.</p><p>More information is available in <a href="ar01s05.html" title="5.&nbsp;XPath Tests">Section&nbsp;5, &ldquo;XPath Tests&rdquo;</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Basic: DOM Tree Walking"></a>2.2.5.&nbsp;DOM Tree Walking</h4></div></div><div></div></div><p>To test pieces of XML by traversing the DOM tree you use
        the <code class="literal">NodeTester</code> class.  Each DOM
        <code class="literal">Node</code> will be passed to a
        <code class="literal">NodeTester</code> implementation you provide.  The
        <code class="literal">AbstractNodeTester</code> class is provided as a
        NullObject Pattern base class for implementations of your
        own.</p><p>More information is available in <a href="ar01s06.html" title="6.&nbsp;DOM Tree Walking">Section&nbsp;6, &ldquo;DOM Tree Walking&rdquo;</a>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Using XMLUnit With JUnit 3.x"></a>2.3.&nbsp;Using XMLUnit With JUnit 3.x</h3></div></div><div></div></div><p>Initially XMLUnit was tightly coupled to JUnit and the
      recommended approach was to write unit tests by inheriting from
      the <code class="literal">XMLTestCase</code> class.
      <code class="literal">XMLTestCase</code> provides a pretty long list of
      <code class="literal">assert...</code> methods that may simplify your
      interaction with XMLUnit's internals in many common
      cases.</p><p>The <code class="literal">XMLAssert</code> class provides the same
      set of <code class="literal">assert...</code>s as static methods.  Use
      <code class="literal">XMLAssert</code> instead of
      <code class="literal">XMLTestCase</code> for your unit tests if you can't
      or don't want to inherit from
      <code class="literal">XMLTestCase</code>.</p><p>All power of XMLUnit is available whether you use
      <code class="literal">XMLTestCase</code> and/or
      <code class="literal">XMLAssert</code> or the underlying API directly.  If
      you are using JUnit 3.x then using the specific classes may prove
      to be more convenient.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Common Configuration Options"></a>2.4.&nbsp;Common Configuration Options</h3></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="JAXP"></a>2.4.1.&nbsp;JAXP</h4></div></div><div></div></div><p>If you are using a JDK 1.4 or later, your Java class
        library already contains the required XML parsers and XSLT
        transformers.  Still you may want to use a different
        parser/transformer than the one of your JDK - in particular
        since the versions shipping with some JDKs are known to
        contain serious bugs.</p><p>As described in <a href="index.html#Configuring XMLUnit" title="1.4.&nbsp;Configuring XMLUnit">Section&nbsp;1.4, &ldquo;Configuring XMLUnit&rdquo;</a>
        there are two main approaches to choose the XML parser of XSLT
        transformer: System properties and setters in the
        <code class="literal">XMLUnit</code> class.</p><p>If you use system properties you have the advantage that
        your choice affects the whole JAXP system, whether it is used
        inside of XMLUnit or not.  If you are using JDK 1.4 or later
        you may also want to review the <a href="http://java.sun.com/j2se/1.4.2/docs/guide/standards/" target="_top">Endorsed
        Standards Override Mechanism</a> to use a different
        parser/transformer than the one shipping with your JDK.</p><p>The second option - using the <code class="literal">XMLUnit</code>
        class - allows you to use different parsers for control and
        test documents, it even allows you to use different parsers
        for different test cases, if you really want to stretch it
        that far.  It may also work for JDK 1.4 and above, even if you
        don't override the endorsed standards libraries.</p><p>You can access the underlying JAXP parser by
        <code class="literal">XMLUnit.newControlParser</code>,
        <code class="literal">XMLUnit.newTestParser</code>,
        <code class="literal">XMLUnit.getControlDocumentBuilderFactory</code>,
        <code class="literal">XMLUnit.getTestDocumentBuilderFactory</code> and
        <code class="literal">XMLUnit.getSAXParserFactory</code> (used by
        <code class="literal">Validator</code>).  Note that all these methods
        return factories or parsers that are namespace aware.</p><p>The various <code class="literal">build...</code> methods in
        <code class="literal">XMLUnit</code> provide convenience layers for
        building DOM <code class="literal">Document</code>s using the configured
        parsers.</p><p>You can also set the class name for the
        <code class="literal">XPathFactory</code> to use when using JAXP 1.3 by
        passing the class name to
        <code class="literal">XMLUnit.setXPathFactory</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="EntityResolver"></a>2.4.2.&nbsp;<code class="literal">EntityResolver</code></h4></div></div><div></div></div><p>You can provide a custom
        <code class="literal">org.xml.sax.EntityResolver</code> for the control
        and test parsers via
        <code class="literal">XMLUnit.setControlEntityResolver</code> and
        <code class="literal">XMLUnit.setTestEntityResolver</code>.
        <code class="literal">Validator</code> uses the resolver set via
        <code class="literal">setControlEntityResolver</code> as well.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="Basic: Element Content Whitespace"></a>2.4.3.&nbsp;Element Content Whitespace</h4></div></div><div></div></div><p>Element content whitespace - also known as ignorable
        whitespace - is whitespace contained in elements whose content
        model doesn't allow text content.  I.e. the newline and space
        characters between <code class="literal">&lt;foo&gt;</code> and
        <code class="literal">&lt;bar&gt;</code> in the following example
        could belong into this category.</p><pre class="programlisting">
&lt;foo&gt;
  &lt;bar/&gt;&lt;/foo&gt;
</pre><p>Using <code class="literal">XMLUnit.setIgnoreWhitespace</code> it
        is possible to make the test and control parser ignore this
        kind of whitespace.</p><p>Note that setting this property to
        <code class="literal">true</code> usually doesn't have any effect since
        it only works on validating parsers and XMLUnit doesn't enable
        validation by default.  It does have an effect when comparing
        pieces of XML, though, since the same flag is used for a
        different purpose as well in that case.  See <a href="ar01s03.html#Whitespace Handling" title="3.8.1.&nbsp;Whitespace Handling">Section&nbsp;3.8.1, &ldquo;Whitespace Handling&rdquo;</a> for more details.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="XSLT Stylesheet Version"></a>2.4.4.&nbsp;XSLT Stylesheet Version</h4></div></div><div></div></div><p>Some features of XMLUnit use XSLT stylesheets under the
        covers, in particular XSLT will be used to strip element
        content whitespace or comments as well as by
        <code class="literal">SimpleXpathEngine</code>.  These stylesheets only
        require a XSLT transformer that supports XSLT 1.0 and will say
        so in the <code class="literal">stylesheet</code> element.</p><p>If your XSLT transformer supports XSLT 2.0 or newer it
        may<sup>[<a href="#ftn.N104DB" name="N104DB">6</a>]</sup> issue a warning for these stylesheets
        which can be annoying.  You can use
        <code class="literal">XMLUnit.setXSLTVersion</code> to make XMLUnit
        change the version attribute to a different value.  Note that
        XMLUnit hasn't been tested with a value other than
        <code class="literal">"1.0"</code>.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="Providing Input to XMLUnit"></a>2.5.&nbsp;Providing Input to XMLUnit</h3></div></div><div></div></div><p>Most methods in XMLUnit that expect a piece of XML as
      input provide several overloads that obtain their input from
      different sources.  The most common options are:</p><div class="itemizedlist"><ul type="disc"><li>A DOM <code class="literal">Document</code>.

          <p>Here you have all control over the document's
          creation.  Such a <code class="literal">Document</code> could as well
          be the result of an XSLT transformation via the
          <code class="literal">Transform</code> class.</p></li><li>A SAX <code class="literal">InputSource</code>.

          <p>This is the most generic way since
          <code class="literal">InputSource</code> allows you to read from
          arbitrary <code class="literal">InputStream</code>s or
          <code class="literal">Reader</code>s.  Use an
          <code class="literal">InputStream</code> wrapped by an
          <code class="literal">InputSource</code> if you want the XML parser to
          pick up the proper encoding from the XML declaration.</p></li><li>A <code class="literal">String</code>.

          <p>Here a DOM <code class="literal">Document</code> is built from
          the input <code class="literal">String</code> using the JAXP parser
          specified for control or test documents - depending on
          whether the input is a control or test piece of XML.</p><p>Note that using a <code class="literal">String</code> assumes
          that your XML has already been converted from its XML
          encoding to a Java <code class="literal">String</code> upfront.</p></li><li>A <code class="literal">Reader</code>.

          <p>Here a DOM <code class="literal">Document</code> is built from
          the input <code class="literal">Reader</code> using the JAXP parser
          specified for control or test documents - depending on
          whether the input is a control or test piece of XML.</p><p>Note that using a <code class="literal">Reader</code> is a
          bad choice if your XML encoding is different from your
          platform's default encoding since Java's IO system won't
          read your XML declaration.  It is a good practice to use one
          of the other overloads rather than the
          <code class="literal">Reader</code> version to ensure encoding has
          been dealt with properly.</p></li></ul></div></div><div class="footnotes"><br><hr align="left" width="100"><div class="footnote"><p><sup>[<a href="#N104DB" name="ftn.N104DB">6</a>] </sup>The W3C recommendation says it
        SHOULD.</p></div></div></div><div class="navfooter"><hr><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="index.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ar01s03.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">XMLUnit Java User's Guide
    <span class="inlinemediaobject"><img src="xmlunit.png" height="100"></span>
  &nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;3.&nbsp;Comparing Pieces of XML</td></tr></table></div></body></html>